<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"
            "http://www.w3.org/TR/REC-html40/loose.dtd">
<HTML>
<HEAD>



<META http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
<META name="GENERATOR" content="hevea 1.08">
<LINK rel="stylesheet" type="text/css" href="embroot.css">
<TITLE>
Overview
</TITLE>
</HEAD>
<BODY >
<A HREF="embroot038.html"><IMG SRC ="previous_motif.gif" ALT="Previous"></A>
<A HREF="embroot036.html"><IMG SRC ="contents_motif.gif" ALT="Up"></A>
<A HREF="embroot040.html"><IMG SRC ="next_motif.gif" ALT="Next"></A>
<HR>

<H2 CLASS="section"><A NAME="htoc68">7.3</A>&nbsp;&nbsp;Overview</H2><UL>
<LI><A HREF="embroot039.html#toc31">Summary of Tcl Commands</A>
</UL>

A peer must already exist before it can participate in peer multitasking:
(i.e. it has already been set up using ec_init (embedded) or ec_remote_init (remote)).<BR>
<BR>
Peer multitasking occur in a <I>multitasking phase</I>, which is a special
way for an ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> side to hand over control to the external
side. Effectively, instead of handing over control to a single peer,
control is handed over repeatedly to all the peers that are participating
in peer multitasking. The control is shared between these peers in a
round-robin fashion, giving rise to a form of co-operative
multitasking. The multitasking is co-operative in that each peer has to
give up control, so that the control can be passed to the next multitasking
peer. A peer multitasking phase is started by calling the predicate
<B>peer_do_multitask/1</B><A NAME="@default156"></A> in ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP>. <BR>
<BR>
To participate in peer multitasking, a peer must be &#8220;registered&#8221;
(initialised) for peer multitasking. This is done by executing the 
procedure <B>ec_multi:peer_register</B><A NAME="@default157"></A>
from Tcl. Once registered, the peer will take part in subsequent
multitasking phases. <BR>
<BR>
The registration can set up three user-defined handlers: the <B>start</B> handler, the <B>interact</B> handler, and the <B>end</B> handler.
During a multitasking phase, control is handed over to a multitasking peer,
which invokes
one of these handlers, and when the handler returns, control is handed
to the next multitasking peer. The interact handler is normally invoked,
except at the start (first) and end (last) of a multitasking phase. In
these cases, the start and end handlers are invoked respectively.<BR>
<BR>
A `type' (specified in the call to <B>peer_do_multitask/1</B><A NAME="@default158"></A>) is associated
with every multitasking phase to allow multitasking phases for different
purposes (distinguished by different `type's). This type is passed to the
handlers as an argument. At the start of a multitasking phase, a peer
should indicate if it is interested in this particular multitasking phase
or not. If no peer is interested in the multitasking
phase, then the multitasking phase enters the end phase after the initial
round of passing control to all the multitasking peers, i.e. control is
passed one more time to the multitasking peers, this time invoking the end
handler. If at least one peer indicates that it is interested in the
multitasking phase, then after the initial start phase, the control will be
repeatedly handed over to each multitasking peer by invoking the interact
handler. This phase is ended when one (or more) peer indicates that the
multitasking phase should end (at which point the end phase will be entered
in which the end handler will be invoked for each multitasking peer). <BR>
<BR>
<A NAME="toc31"></A>
<H3 CLASS="subsection"><A NAME="htoc69">7.3.1</A>&nbsp;&nbsp;Summary of Tcl Commands</H3>
Here is a more detailed description of the Tcl procedures:
<DL CLASS="description" COMPACT=compact><DT CLASS="dt-description">
<A NAME="@default159"></A><B>ec_multi:peer_register <I>?Multitask handlers</I></B><DD CLASS="dd-description"><BR>
Registers for peer multitasking, and setup the (optional) multitask handlers.
 There handlers can be specified: a) start, invoked at the start of a
 multitasking phase; b) end, invoked at the end of a multitasking
 phase, and c) interact, invoked at other times when the peer is
 given control during a multitasking phase. <B>Multitask handlers</B>
 is a list specifying the handlers, where each handler is specified
 as two list elements of the form: <TT>type name</TT>,
 where type is either <B>start</B>, <B>end</B> or <B>interact</B>, and
 name is the name of the user defined handler. For example:
<PRE CLASS="verbatim">
      ec_multi:peer_register [list interact tkecl:multi_interact_handler 
            start tkecl:multi_start_handler end tkecl:multi_end_handler]
</PRE>When control is handed over to the peer during a peer multitasking
 phase, the appropriate handler (if defined) is invoked. When the
 handler returns, control is handed back to ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> (and passed
 to the next multitasking peer). Note 
 that events are not processed while the peer does not have control.
 The Tcl command <B>update</B> is therefore called each time the peer
 is given control, to allow any accumulated events to be processed.
 As long as the peer
 is given control frequently enough, then any interactions with the
 peer would appear to be continuous.<BR>
<BR>
The handlers are invoked with the `type' of the multitasking phase
 supplied as the first argument. This will for example allow the
 start handler to determine if it is interested in this multitasking
 phase. They can also set one of the following return codes:
<DL CLASS="description" COMPACT=compact><DT CLASS="dt-description">
<B>continue</B><DD CLASS="dd-description"> indicates that the peer wants to continue the multitasking
 phase. In particular, this should be returned by the start handler if it is
 interested in the multitasking phase. Note that the multitasking phase is
 not guaranteed to continue, as it can be terminated by another
 multitasking peer.
<DT CLASS="dt-description"><B>terminate</B><DD CLASS="dd-description"> indicates the termination of a multitasking phase. The
 multitasking phase will enter the end phase, where the end handlers
 will be invoked once per peer before the multitasking phase finishes.
</DL>
 For example, here is the start handler used in the Tk development
 tools:
<PRE CLASS="verbatim">
proc tkecl:multi_start_handler {type} {

    switch $type {
        tracer {
            # multitasking phase is `tracer'
            # only do handling of port if the tracer window exists
            if [winfo exists .ec_tools.ec_tracer] {
                tkecl:handle_tracer_port_start
                set of_interest  continue
            }
        }
        default {
            set of_interest no
            # do nothing
        }
    }

    return $of_interest
}

</PRE>
An error is raised if this procedure is called while the peer is already
registered for multitasking.<BR>
<BR>
<DT CLASS="dt-description"><A NAME="@default160"></A><B>ec_multi:peer_deregister</B><DD CLASS="dd-description"><BR>
Deregisters peer from multitasking. After calling this procedure, the
 peer will not participate in any further multitasking. If this
 procedure is called during a multitasking phase, the peer will not
 participate further in that multitasking phase once control is
 returned. The multitasking phase will continue, unless there are no
 multitasking peers left, in which case an error will be raised on the 
 ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> side. The peer multitask control queue will be
 automatically closed.<BR>
<BR>
An error is raised if this procedure is called while the peer is
 not registered for multitasking.<BR>
<BR>
<DT CLASS="dt-description"><A NAME="@default161"></A><B>ec_multi:get_multi_status</B><DD CLASS="dd-description"><BR>
Returns the current peer multitasking status for the peer. The values
 can be:
<UL CLASS="itemize"><LI CLASS="li-itemize">
not_registered: the peer is not registered for peer multitasking.
<LI CLASS="li-itemize">off: the peer is registered for peer multitasking, but is not
 currently in a multitasking phase.
<LI CLASS="li-itemize">on: the peer is registered for peer multitasking, and is currently in
 a multitasking phase.
</UL><BR>
Note that the peer multitasking code is implemented using peer queue
handlers. Thus, the peer multitask status is set to `on' 
before the multitask start handler is called, but <I>after</I> the
`ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP> end' handler.
Conversely, the peer multitask status is set to
`off' after the multitask end handler, but <I>before</I> the ECL<SUP><I>i</I></SUP>PS<SUP><I>e</I></SUP>
start handler.
</DL>
<HR>
<A HREF="embroot038.html"><IMG SRC ="previous_motif.gif" ALT="Previous"></A>
<A HREF="embroot036.html"><IMG SRC ="contents_motif.gif" ALT="Up"></A>
<A HREF="embroot040.html"><IMG SRC ="next_motif.gif" ALT="Next"></A>
</BODY>
</HTML>
